Apple WWDC 1996/WWDC96_1996 (CD).toast/Technology Materials/MacApp Release 10/MacApp Release 10 - HD Ready/Libraries/Views/Includes/UTEView.h

Text File | 1996-04-03 | 21.8 KB | 597 lines | [TEXT/MPS ]

// UTEView.h
// Copyright © 1986-96 by Apple Computer, Inc. All rights reserved.


#ifndef __UTEVIEW__
#define __UTEVIEW__

// MacApp

#ifndef __UVIEW__
#include "UView.h"
#endif

// Toolbox

#ifndef __TEXTEDIT__
#include <TextEdit.h>
#endif

// ANSI

#ifndef __LIMITS__
#include <limits.h>
#endif

//----------------------------------------------------------------------------------------
// Forward and external class declarations
//----------------------------------------------------------------------------------------

class TDocument;
class TEditText;
class TScroller;
class TTECommand;
class TTEStyleCommand;
class TTETypingCommand;
class TToolboxEvent;


//----------------------------------------------------------------------------------------
// Constants
//----------------------------------------------------------------------------------------

const unsigned short kUnlimited = SHRT_MAX;    // The maximum number of characters in the
                                                // fText of a TTEView object

const Boolean kWithStyle = TRUE;                // Parameters to TTEView::ITEView
const Boolean kWithoutStyle = FALSE;

const Boolean kSaveCurrentChars = TRUE;            // Parameter to ITECommand

const unsigned char Chr00 = 0;                // Needed for ControlCharSet

const unsigned char Chr1F = 31;

const VCoordinate kMinAhead = 96;                // Default value for fMinAhead


//----------------------------------------------------------------------------------------
// Typedefs
//----------------------------------------------------------------------------------------

typedef long ControlCharSet;

//----------------------------------------------------------------------------------------
// TTEView: TTEView is a view subclass representing a TextEdit record. TextEdit is the
// simple text-editing facility built into the Macintosh ROM. The purpose of a TEView is
// to make TextEdit function properly in a MacApp environment, for things like scrolling,
// printing, page breaks, and command handling
//----------------------------------------------------------------------------------------

class TTEView : public TView
{
    MA_DECLARE_CLASS;

public:

    //------------------------------------------------------------------------------------
    // Initialize and Free
    //------------------------------------------------------------------------------------

    TTEView();
        // Constructor

    void ITEView(TDocument* itsDocument,
                                TView* itsSuperView,
                                const VPoint& itsLocation,
                                const VPoint& itsSize,
                                SizeDeterminer itsHDeterminer,
                                SizeDeterminer itsVDeterminer,
                                const VRect& itsInset,
                                const TextStyle& itsTextStyle,
                                short itsJustification,
                                Boolean itsStyleType,
                                Boolean itsAutoWrap);
        // For Initialization of procedurally created TEView.

    virtual TObject* Clone();
        // calls Inherited::Clone and then clones owned objects

    virtual ~TTEView();
        // Frees the TERecord and optionally fText, then Inherited::Free.


    //------------------------------------------------------------------------------------
    // Standard signature support.
    //------------------------------------------------------------------------------------

    virtual IDType GetStandardSignature();    // override
        // Returns this class's standard signature.


    //------------------------------------------------------------------------------------
    // Stream I/O protocol support.
    //------------------------------------------------------------------------------------

    virtual void ReadFields(TStream* aStream);    // override

    virtual void WriteFields(TStream* aStream);    // override


    //------------------------------------------------------------------------------------
    // View method overrides
    //------------------------------------------------------------------------------------

    virtual void MakeTERecord();
        // Called with grafport properly set, to create the actual TE Record


    //------------------------------------------------------------------------------------
    //  Commands and Menus
    //------------------------------------------------------------------------------------

    virtual void DoKeyEvent(TToolboxEvent* event);
        // Handles keystrokes

    virtual TTECommand* DoMakeEditCommand(CommandNumber aCommandNumber);
        // Make a command for handling edit menu stuff

    virtual TTEStyleCommand* DoMakeStyleCommand(const TextStyle& aStyle,
                                                       CommandNumber itsCommandNumber,
                                                       short itsMode);
    // Make a style change command

    virtual TTETypingCommand* DoMakeTypingCommand(const CStr2& ch);
        // Make a typing command for handling the new character[s]

    virtual void DoMenuCommand(CommandNumber aCommandNumber);
        // Handles menu commands

    virtual void DoMouseCommand(VPoint& theMouse,
                                       TToolboxEvent* event,
                                       CPoint hysteresis);
        // Handles mousepresses

    virtual void DoneTyping();
        // No further typing can occur for the current typing command

    virtual void DoSetupMenus();
        // Sets up menus

    virtual void SetActive(Boolean state);
        // Calls TEActivate or TEDeactivate

    virtual void BecameWindowTarget();        // Override

    virtual void ResignedWindowTarget();        // Override

    virtual void BecameTarget();                // Override

    virtual void ResignedTarget();            // Override

    virtual void SetEnable(Boolean state);
        // Resets the view's idle

    virtual TEditText* GetEditText();
        // Get the edit text view, if any, that owns this TE view.


    //------------------------------------------------------------------------------------
    //  Screen Display
    //------------------------------------------------------------------------------------

    virtual Boolean DoIdle(IdlePhase phase);
        // Blinks the insertion CPoint

    virtual void Draw(const VRect& area);
        // Draw the text in a frame or on the printed page

    virtual void ShowReverted();
        // Make sure line starts are correct before redisplay


    //------------------------------------------------------------------------------------
    //  Size Changes
    //------------------------------------------------------------------------------------

    virtual void BeInPort(GrafPtr itsPort);
        // Now that a grafport is established for the view, tells TextEdit about it

    virtual void BeInScroller(TScroller* itsScroller);
        // Gives us a chance to set the scroll parameters

    virtual VRect CalcMinFrame();
        // Compute the minimum size of the view

    virtual long CalcRealHeight();
        // Calculate true height of record, including last character if it is a carriage
        // return

    virtual long CalcRealWidth();
        // Calculate true width of record.Only supported for NON-styled TE Records right
        // now

    virtual void ComputeFrame(VRect& newFrame);
        // Compute the actual size of the view

    virtual void SetFrame(const VRect& newFrame, Boolean invalidate);
        // Installs the new size for both the View and TextEdit

    virtual void InvalidateFrameDifference(const VRect& oldFrame, const VRect& newFrame); // Override
        // Overridden to account for fInset

    virtual void UpdateCoordinates();// override
        // Keeps the TE in synch with any VSpace or QDSpace origin changes.

    virtual void SynchView(Boolean redraw);
        // Keeps view metrics in synch after TextEdit operation. If redraw is true then
        // ScrollSelectionIntoView is called to make sure the selection is visible.

    virtual VPoint OffsetToPt(short offset);
        // Converts offset in text to view coordinates.

    virtual short OffsetToLine(short offset);
        // Returns the line number that contains the offset

    virtual short OffsetToLineStart(short offset);
        // Returns the offset of the start of the line that contains the offset

    virtual short OffsetToLineEnd(short offset);
        // Returns the offset of the end of the line that contains the offset

    virtual short PtToOffset(const VPoint& aPoint);
        // Converts a view CPoint to an offset in the text.

    virtual Boolean WordBounds(short charPos,
                                      short& wordStart,
                                      short& wordEnd);
        // charPos is the offset of a specific character in the text Returns: true iff
        // that character is part of a word wordStart = offset of first character of the
        // word wordEnd= offset of final character of the word Note: these are CHARACTER
        // offsets, not CURSOR POSITIONS.


    //------------------------------------------------------------------------------------
    // NOTE -- These methods apply only to a TEView installed as the view in the Clipboard
    //------------------------------------------------------------------------------------

    virtual Boolean ContainsClipType(ResType aType);
        // Determines whether the indicated clipboard type can be produced by the view

    virtual long GivePasteData(Handle aDataHandle,
                                      ResType dataType);
        // Supplies data to be PASTED by some requesting PASTE command

    virtual void WriteToDeskScrap();
        // Produces TEXT data for the Desk Scrap when called upon to do so


    //------------------------------------------------------------------------------------
    //  Miscellaneous
    //------------------------------------------------------------------------------------

    virtual void AutoScrolling(Boolean doScrolling);
        // Set TERecord auto scrolling to given value via TEAutoScroll

    virtual Boolean ClickLoop();
        // Forwarded to from the global routine: ClickLoopForTTEView which was set as the
        // TE's ClickLoop.Typically handles autoscrolling for the view.

    virtual void CalcSelLoc(VRect& selectionRect);
        // Calculates the location of the current Selection

    virtual void SetSelection(short NewSelStart,
                                     short NewSelEnd,
                                     Boolean redraw);

    virtual void GetSelectionString(CStr255& selection);
        // Returns the selected text as a CStr255. If the selection is longer than 255
        // characters, the first 255 characters are returned

    virtual short GetNumberOfChars();
        // Returns the number of characters stored in the text handle in a script
        // manager compatible way.

    short GetCharacterOffset(short fromOffset);
        // Returns the offset of the beginning of the proposed offset
        // Correcting for multibyte characters

    short GetBytesInCharacter(short atOffset);
        // Returns the number of bytes in the character pointed

    short GetNextCharacterOffset(short fromOffset);
        // Returns the offset of the character following this offset
        // Correcting for multibyte characters

    short GetPrevCharacterOffset(short fromOffset);
        // Returns the offset of the character before this offset
        // Correcting for multibyte characters

    virtual void ChangeWrap(Boolean newAutoWrap,
                                   Boolean redraw);
        // Changes auto-wrapping behavior, redrawing if requested

    virtual Boolean ContinuousStyle(short firstChar,
                                           short lastChar,
                                           short& mode,
                                           TextStyle& aStyle);
        // Returns true if the style of the characters within the given range is wholly
        // continuous. The style attributes to check are specified by mode, which has the
        // same meaning as in the TextEdit call TESetStyle. Attributes which are
        // continuous are returned in aStyle, with the appropriate bits set in mode. Font
        // style attribute bits are individually checked across the selection range, and
        // returned set to 1 if that attribute is continuous.

    virtual void ExtractStyles(TEStyleHandle& theStyles,
                                      STHandle& theElements);
        // Extract handles to style information for a TextEdit record, presumably for the
        // purpose of storing the data to disk. Note that line heights can be
        // recalculated, and as such don't need to be stored.

    virtual Handle ExtractText() const;
        // For sake of completeness. Extract handle to text, presumably for the purpose of
        // storing the text externally (perhaps to disk).

    virtual void RecalcText();
        // Tells TextEdit to recompute linestarts

    virtual void ScrollSelectionIntoView(Boolean redraw);    // Override
        // Scrolls the selection into view -- called after Commands are done or undone If
        // auto scrolling is on, calls TESelView to do the right thing

    virtual void SetJustification(short newJust,
                                         Boolean redraw);
        // Sets the TERecord to the given justification. If redraw is true then the view
        // is redrawn by calling ForceRedraw. Otherwise it is assumed the called will get
        // the view redrawn.

    virtual void SetOneStyle(short theStart,
                                    short theEnd,
                                    short theMode,
                                    const TextStyle& theStyle,
                                    Boolean redraw);
        // Sets a text style continuously over a range. In unstylish TERecords, the style
        // is set across the entire record. If redraw is true then the text is redrawn.

    virtual void SetText(const CStr255& theText);
        // Convenience routine, to save from having to create a handle just to pass to
        // StuffText. Note that if fSavedTEHandle already holds a saved handle, it will be
        // disposed before StuffText is called.

    virtual Boolean SpaceForStyles(long rangeStart,
                                          long rangeEnd);
        // Returns true if there is enough memory to hold the styles over the given range
        // in the TERecord

    virtual void StuffStyles(TEStyleHandle theStyles,
                                    STHandle theElements);
        // Installs style information, presumably fetched from disk, into the TextEdit
        // record.

    virtual void StuffText(Handle theText);
        // Installs text into the TextEdit record. Note that this destroys any existing
        // style information -- StuffStyles should be called if styles are to be attached
        // to this text information

    virtual void StuffTERects(const CRect& newTERect);
        // installs "newTERect" as the dest & view CRect of the TextEdit record


    //------------------------------------------------------------------------------------
    //  Printing
    //------------------------------------------------------------------------------------

    virtual VCoordinate DoBreakFollowing(VHSelect vhs,
                                                VCoordinate previousBreak,
                                                Boolean& automatic);
        // Computes the next page-break following 'previousBreak' in direction given by
        // 'vhs'

    virtual VPoint DoCalcViewPerPage();
        // Computes how much of the view is to be allocated to each printed page

    virtual void DoSetPageOffset(const VPoint& coord);
        // At printing time, determine the location of the 'interior' (body) of the page

    virtual VRect GetPrintExtent();
        // Print extent is the view's extent minus the insets.

#if qDrag

    //------------------------------------------------------------------------------------
    //  Drag/Drop Support
    //------------------------------------------------------------------------------------

    virtual RgnHandle DoMakeDragCursorRegion(); // Override
        // Create and return a description of the drag region in local coordinates

    virtual Boolean WillDrag(const VPoint& theMouse, const RgnHandle dragCursorRegion); // Override
        // Give a mouse point in local coordinates, returns true if clicking the mouse
        // would initiate a drag operation

    virtual short GetWillDragCursorID();    // Override
        // display quickdraw arrow cursor

    virtual short GetIsDraggingCursorID();    // Override
        // display quickdraw arrow cursor

    virtual void DoAddDragContent(); // Override
        // Install flavors into the current drag operation

    virtual Boolean WillAcceptDrop(CDragItemIterator& dragItemIterator); // Override
        // Return true if the drag contains exactly one item and is available as
        // text

    virtual void DoDragEnter(); // Override
        // Prepare to track the drag

    virtual void DoDragWithin(const VPoint& localMouse); // Override
        // Track insertion location and manage drawing the blinking caret.

    virtual void DoDragLeave(); // Override
        // Clean up after being the drag target.

    virtual TCommand* DoMakeDragDropCommand(CommandNumber         itsCommandNumber,
                                            CDragItemIterator&     dragItemIterator);
        // Create a command to manage a drag or drop operation.

    virtual void DoFulfillPromise(TDragItem *promisedItem); // Override
        // Provide promised flavor data

    virtual void DrawCaret( short offset);
        // Given an offset, draw or undraw the blinking caret while a drag is being tracked.

#endif // qDrag


//----------------------------------------------------------------------------------------
// static member functions
//----------------------------------------------------------------------------------------
public:
    static void SetSelect(short theStart, short theEnd, TEHandle hTE);
        // For those times when we don't want the selection range hilited when changed

    static pascal Boolean ClickLoopForTTEView();
        // Called from TextEdit when the mouse is down forwards to TTEView::ClickLoop so that
        // autoscrolling may be done.
        // NOTE: this routine requires the pascal keyword because the Toolbox requires it

#if qDebug
    static void DumpTERecord(TEHandle aTEH);
        // writes salient information about the TERecord out to the Debug window
#endif

    static short TEIsFrontOfLine(short offset, TEHandle theTE);

    static short TEGetLine(short offset, TEHandle theTE);

    static Boolean IsBlank( Handle theText, short offset, short& length );

protected:
#if qDebug
    static void WriteChar(short index, Handle hText);
#endif

//----------------------------------------------------------------------------------------
// data members
//----------------------------------------------------------------------------------------
public:

    TextStyle fTextStyle;                        // Current style of text

    VRect fInset;                                // Amount to inset text from edges of view

    TTETypingCommand* fTypingCommand;            // The current TE Typing command relating
                                                // to me, if any

    TEHandle fHTE;                                // Handle to the actual TextEdit object

    Handle fText;                                // The text in the TEHandle

    Handle fSavedTEHandle;                        // Saved handle from TENew

    VCoordinate fLastHeight;                    // Last checked height of record. If the
                                                // record is stylish, this represents the
                                                // height in pixels. For old-style
                                                // records, equals number of lines.

    VCoordinate fLastWidth;                        // Last checked width of record. Not
                                                // currently used If the TE is styled,
                                                // this represents the width in pixels.

    VCoordinate fMinAhead;                        // Minimum amount by which to autoscroll
                                                // ahead when scrolling selection into
                                                // view.(When typing etc.

    VCoordinate fLastPageBreak;                    // Caches last page break computed.

    CommandNumber fKeyCommandNumber;            // Will be used as the CString number for
                                                // "Undo Typing"

    ControlCharSet fControlChars;                // Control chars accepted in text

    unsigned short fMaxChars;                    // Maximum number of chars to accept into
                                                // fText. Default is SHRT_MAX; stuff to
                                                // different value if you want to limit
                                                // max chars to fewer than SHRT_MAX

    ResNumber fTextStyleRsrcID;                    // Rsrc ID of 'TxSt' resource which has
                                                // TextStyle information.

    short fJustification;                        // Current justification of text record

    unsigned short fLastLine;                    // Last line of text of the last page
                                                // break

    short fSelAnchor;                            // current selection "anchor"

    short fUpDownH;                                // for repeated Up- and/or Down-arrowing

    Boolean fPreferOutline;                        // prefer outline fonts?

    Boolean fAcceptsChanges;                    // Set to false to have text which will
                                                // not accept any change, such as text on
                                                // the Clipboard, or perhaps received mail

    Boolean fStyleType;                            // Set to kWithStyle if record is styled

    Boolean fAutoWrap;                            // Set to false for line wrapping at CR's
                                                // only

    Boolean fFreeText;                            // Determines if fText should be freed on
                                                // Free.

    Boolean fSpecsChanged;                        // Something recently happened which could
                                                // effect font/style/size/ color menu item
                                                // updating. Should be reset to false when
                                                // application has taken the appropriate
                                                // action.

    Boolean fUpDown;                            // used to keep track of horizontal
                                                // position

    //------------------------------------------------------------------------------------
    //  Drag and Drop Data
    //------------------------------------------------------------------------------------
#if qDrag
public:
    RgnHandle fHiliteRgn;

    unsigned long fLastCaretTime;

    short fLastCaretOffset;

    Boolean fCaretIsShown;

#endif

//----------------------------------------------------------------------------------------
// static data members
//----------------------------------------------------------------------------------------
public:
    static TEClickLoopUPP fgDefClickLoopProc;                // Standard TextEdit click loop routine

    // The following are considered private, but appear in the interface in case you need to
    // override a method that uses one of these.
    static TTEView* fgCurrTEView;                            //For the benefit of ClickLoopForTTEView only

    static TEClickLoopUPP fgClickLoopProc;
        // The fgClickLoopProc global is used for PPC compatibility.  In the case of a
        // PPC application, we create a single UniversalProcPtr for ClickLoopForTTEView.

    #if qDebug
    static Boolean fgTEIntenseDebugging;
    #endif
};

//----------------------------------------------------------------------------------------
// Global procedure declarations
//----------------------------------------------------------------------------------------

void InitUTEView();
    // Initialize TEView unit.

#endif